/*
 * \brief  Parent interface
 * \author Norman Feske
 * \date   2006-05-10
 */

/*
 * Copyright (C) 2006-2009 Norman Feske
 * Genode Labs, Feske & Helmuth Systementwicklung GbR
 *
 * This file is part of the Genode OS framework, which is distributed
 * under the terms of the GNU General Public License version 2.
 */

#ifndef _INCLUDE__PARENT__PARENT_H_
#define _INCLUDE__PARENT__PARENT_H_

#include <base/exception.h>
#include <base/session_control.h>
#include <session/capability.h>
#include <root/capability.h>

namespace Genode {

	class Parent : public Session_control
	{
		public:

			enum { MSGBUF_SIZE = 256 };


			/*********************
			 ** Exception types **
			 *********************/

			class Service_denied : public Exception { };
			class Quota_exceeded : public Exception { };

		protected:

			enum Opcode { EXIT, ANNOUNCE, SESSION, TRANSFER_QUOTA, CLOSE };

		public:

			virtual ~Parent() { }

			/**
			 * Tell parent to exit the program
			 */
			virtual void exit(int exit_value) = 0;

			/**
			 * Announce service to the parent
			 */
			virtual int announce(const char *service_name,
			                     Root_capability service_root) = 0;

			/**
			 * Create session to a service
			 *
			 * \param service_name     name of the requested interface
			 * \param args             session constructor arguments
			 *
			 * \throw Service_denied   parent denies session request
			 * \throw Quota_exceeded   our own quota does not suffice for
			 *                         the creation of the new session
			 *
			 * \return                 capability to new session
			 *
			 * By convention, an argument value for 'ram_quota' must be
			 * specified in 'args'. The specified amount of RAM will be
			 * donated to the session-providing service.
			 */
			virtual Session_capability session(const char *service_name,
			                                   const char *args) = 0;

			/**
			 * Transfer our quota to the server that provides the specified session
			 *
			 * \param to_session      recipient session
			 * \param amount          description of the amount of quota to transfer
			 *
			 * \throw Quota_exceeded  quota could not be transferred
			 *
			 * The 'amount' argument has the same principle format as the 'args'
			 * argument of the 'session' function.
			 * The error case indicates that there is not enough unused quota on
			 * the source side.
			 */
			virtual void transfer_quota(Session_capability to_session,
			                            const char *amount) = 0;
	};
}

#endif /* _INCLUDE__PARENT__PARENT_H_ */
